<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>wait</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_001_014_2828">&nbsp;</a>NAME</h4><blockquote>
wait - await process completion
</blockquote><h4><a name = "tag_001_014_2829">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

wait <b>[</b><i>pid</i>...<b>]</b>
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_2830">&nbsp;</a>DESCRIPTION</h4><blockquote>
When an asynchronous list (see
<xref href=asyncl><a href="chap2.html#tag_001_009_003">
Lists
</a></xref>)
is started by the
shell, the process ID
of the last command in
each element of the asynchronous list
becomes known in the current shell execution environment; see
<xref href=shexenv><a href="chap2.html#tag_001_012">
Shell Execution Environment
</a></xref>.
<p>
If the
<i>wait</i>
utility is invoked with no operands, it will wait
until all process IDs known to the invoking shell have
terminated and exit with a zero exit status.
<p>
If one or more
<i>pid</i>
operands are specified that represent known process IDs, the
<i>wait</i>
utility will wait until all of them have terminated.
If one or more
<i>pid</i>
operands are specified that represent unknown process IDs,
<i>wait</i>
will treat them as if they
were known process IDs that exited with exit status 127.
The exit status returned by the
<i>wait</i>
utility will be the exit status of
the process requested by the last
<i>pid</i>
operand.
<p>
The known process IDs are applicable only for invocations of
<i>wait</i>
in the current shell execution environment.
</blockquote><h4><a name = "tag_001_014_2831">&nbsp;</a>OPTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_2832">&nbsp;</a>OPERANDS</h4><blockquote>
The following operand is supported:
<dl compact>

<dt><i>pid</i><dd>One of the following:
<ol>

<li>
The unsigned decimal integer process ID of a command,
for which the utility is to wait for the termination.

<li>
A job control job ID (see
the <b>XBD</b> specification, <a href="../xbd/glossary.html"><b>Glossary</b>&nbsp;</a> )
that identifies a background process group to be waited for.
The job control job ID notation
is applicable only for invocations of
<i>wait</i>
in the current shell execution environment;
see
<xref href=shexenv><a href="chap2.html#tag_001_012">
Shell Execution Environment
</a></xref>.
The exit status of
<i>wait</i>
is determined by the last command in the pipeline.
<dl><dt><b>Note:</b>
<dd>The job control job ID type of
<i>pid</i>
is available on systems supporting both the
job control option
and the User Portability Utilities Option,
which applies to all XSI-conformant systems.
</dl>
<p>
</ol>
<p>
</dl>
</blockquote><h4><a name = "tag_001_014_2833">&nbsp;</a>STDIN</h4><blockquote>
Not used.
</blockquote><h4><a name = "tag_001_014_2834">&nbsp;</a>INPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_2835">&nbsp;</a>ENVIRONMENT VARIABLES</h4><blockquote>
The following environment variables affect the execution of
<i>wait</i>:
<dl compact>

<dt><i>LANG</i><dd>Provide a default value for the internationalisation variables
that are unset or null.
If
<i>LANG</i>
is unset or null, the corresponding value from the
implementation-dependent default locale will be used.
If any of the internationalisation variables contains an invalid setting, the
utility will behave as if none of the variables had been defined.


<dt><i>LC_ALL</i><dd>
If set to a non-empty string value,
override the values of all the other internationalisation variables.

<dt><i>LC_CTYPE</i><dd>
Determine the
locale for the interpretation of sequences of bytes of text data as
characters (for example, single- as opposed to multi-byte characters
in arguments).

<dt><i>LC_MESSAGES</i><dd>
Determine the locale that should be used to affect
the format and contents of diagnostic
messages written to standard error.

<dt><i>NLSPATH</i><dd>
Determine the location of message catalogues
for the processing of
<i>LC_MESSAGES .
</i>
</dl>
</blockquote><h4><a name = "tag_001_014_2836">&nbsp;</a>ASYNCHRONOUS EVENTS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_2837">&nbsp;</a>STDOUT</h4><blockquote>
Not used.
</blockquote><h4><a name = "tag_001_014_2838">&nbsp;</a>STDERR</h4><blockquote>
Used only for diagnostic messages.
</blockquote><h4><a name = "tag_001_014_2839">&nbsp;</a>OUTPUT FILES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_2840">&nbsp;</a>EXTENDED DESCRIPTION</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_2841">&nbsp;</a>EXIT STATUS</h4><blockquote>
If one or more operands were specified, all of them have
terminated or were not
known by the invoking shell, and the
status of the last operand specified is known, then the exit status of
<i>wait</i>
will be the exit status information of the
command indicated by the last operand specified.
If the process terminated abnormally due to the
receipt of a signal, the exit status will be greater than 128
and will be distinct from the exit status generated by other
signals, but the exact value is unspecified.
(See the
<i><a href="kill.html">kill</a></i>
<b>-l</b>
option.)
Otherwise, the
<i>wait</i>
utility will exit with one of the following values:
<dl compact>

<dt>0<dd>The
<i>wait</i>
utility was invoked with no operands and all
process IDs known by the invoking shell have terminated.

<dt>1-126<dd>The
<i>wait</i>
utility detected an error.

<dt>127<dd>The command identified by the last
<i>pid</i>
operand specified is unknown.

</dl>
</blockquote><h4><a name = "tag_001_014_2842">&nbsp;</a>CONSEQUENCES OF ERRORS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_2843">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
On most implementations,
<i>wait</i>
is a shell built-in.
If it is called in a subshell or separate utility execution environment,
such as one of the following:
<pre>
<code>
(wait)
nohup wait ...
find . -exec wait ... \;
</code>
</pre>
it will return immediately because there will be no known
process IDs to wait for in those environments.
<p>
Historical implementations of interactive shells have discarded
the exit status of terminated background processes before each
shell prompt.
Therefore, the status of background processes was
usually lost unless it terminated while
<i>wait</i>
was waiting for it.
This could be a serious problem when a job that was expected to
run for a long time actually terminated quickly with a syntax or
initialisation error because the exit status returned was
usually zero if the requested process ID was not found.
This specification requires the implementation to keep the status of
terminated jobs available until the status is requested, so that
scripts like:
<pre>
<code>
j1&amp;
p1=$!
j2&amp;
wait $p1
echo Job 1 exited with status $?
wait $!
echo Job 2 exited with status $?
</code>
</pre>
will work without losing status on any of the jobs.
The shell is allowed to discard the status of any process that it
determines the application cannot get the process ID from the shell.
It is also required to remember only
{CHILD_MAX}
number of processes in this way.
Since the only way to get the process ID from the shell
is by using the
"!"
shell parameter, the shell is allowed to
discard the status of an asynchronous list if
$!
was not referenced before another asynchronous list was started.
(This means that the shell only has to keep the status of the
last asynchronous list started if the application did not
reference
$!.
If the implementation of the shell is smart
enough to determine that a reference to
$!
was not saved
anywhere that the application can retrieve it later, it can
use this information to trim the list of saved information.
Note also that a successful call to
<i>wait</i>
with no operands
discards the exit status of all asynchronous lists.)
<p>
If the exit status of
<i>wait</i>
is greater than 128, there is no way
for the application to know if the waited-for process exited
with that value or was killed by a signal.
Since most utilities
exit with small values, there is seldom any ambiguity.
Even in the ambiguous cases, most applications just need to know that
the asynchronous job failed; it does not matter whether it
detected an error and failed or was killed and did not complete
its job normally.
</blockquote><h4><a name = "tag_001_014_2844">&nbsp;</a>EXAMPLES</h4><blockquote>
Although the exact value used when a process is terminated by a
signal is unspecified, if it is known that a signal terminated a
process, a script can still reliably figure out which signal using
<i><a href="kill.html">kill</a></i>
as shown by the following script:
<pre>
<code>
sleep 1000&amp;
pid=$!
kill -kill $pid
wait $pid
echo $pid was terminated by a SIG$(kill -l $?) signal.
</code>
</pre>
<p>
If the following sequence of commands is run in less
than 31 seconds:
<pre>
<code>
sleep 257 | sleep 31 &amp;
jobs -l %%
</code>
</pre>
<p>
either of the following commands will return the exit status
of the second
<i><a href="sleep.html">sleep</a></i>
in the pipeline:
<pre>
<code>
wait <i>&lt;pid of sleep 31&gt;</i>
wait %%
</code>
</pre>
</blockquote><h4><a name = "tag_001_014_2845">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_001_014_2846">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="sh.html">sh</a></i>,
the <b>XSH</b> specification description of
<i><a href="../xsh/waitpid.html">waitpid()</a></i>.
<br>
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
